---
title: Quickstart
description: Create your first AI Agent from scratch
---

import { Steps } from '@astrojs/starlight/components';
import { Code } from '@astrojs/starlight/components';
import quickstartExample from '../../../../../examples/docs/quickstart/index.ts?raw';

## Project Setup

<Steps>

1. Create a project and initialize npm. You'll only need to do this once.

   ```bash
   mkdir my_project
   cd my_project
   npm init -y
   ```

2. Install the Agents SDK.

   ```bash
   npm install @openai/agents zod@3
   ```

3. Set an OpenAI API key. If you don't have one, follow [these instructions](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) to create an OpenAI API key.

   ```bash
   export OPENAI_API_KEY=sk-...
   ```

   Alternatively you can call `setDefaultOpenAIKey('<api key>')` to set the key
   programmatically and use `setTracingExportApiKey('<api key>')` for tracing.
   See [the config guide](/openai-agents-js/guides/config) for more details.

</Steps>

## Create your first agent

Agents are defined with instructions and a name.

```typescript
import { Agent } from '@openai/agents';

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});
```

## Run your first agent

You can use the `run` method to run your agent. You trigger a run by passing both the agent you
want to start on and the input you want to pass in.

This will return a result that contains the final output and any actions that were performed
during that run.

```typescript
import { Agent, run } from '@openai/agents';

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const result = await run(agent, 'When did sharks first appear?');

console.log(result.finalOutput);
```

## Give your agent tools

You can give an agent tools to use to look up information or perform actions.

```typescript
import { Agent, tool } from '@openai/agents';

const historyFunFact = tool({
  // The name of the tool will be used by the agent to tell what tool to use.
  name: 'history_fun_fact',
  // The description is used to describe **when** to use the tool by telling it **what** it does.
  description: 'Give a fun fact about a historical event',
  // This tool takes no parameters, so we provide an empty Zod Object.
  parameters: z.object({}),
  execute: async () => {
    // The output will be returned back to the Agent to use
    return 'Sharks are older than trees.';
  },
});

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
  // Adding the tool to the agent
  tools: [historyFunFact],
});
```

## Add a few more agents

Additional agents can be defined similarly to break down problems into smaller parts and have your
agent be more focused on the task at hand. It also allows you to use different models for different
problems by defining the model on the agent.

```typescript
const historyTutorAgent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const mathTutorAgent = new Agent({
  name: 'Math Tutor',
  instructions:
    'You provide help with math problems. Explain your reasoning at each step and include examples',
});
```

## Define your handoffs

In order to orchestrate between multiple agents, you can define `handoffs` for an agent. This will
enable the agent to pass the conversation on to the next agent. This will happen automatically
during the course of a run.

```typescript
// Using the Agent.create method to ensures type safety for the final output
const triageAgent = Agent.create({
  name: 'Triage Agent',
  instructions:
    "You determine which agent to use based on the user's homework question",
  handoffs: [historyTutorAgent, mathTutorAgent],
});
```

After your run you can see which agent generated the final response by looking at the `finalAgent`
property on the result.

## Run the agent orchestration

The Runner is in handling the execution of the invidiual agents, any potential handoffs and tool
executions.

```typescript
import { run } from '@openai/agents';

async function main() {
  const result = await run(triageAgent, 'What is the capital of France?');
  console.log(result.finalOutput);
}

main().catch((err) => console.error(err));
```

## Putting it all together

Let's put it all together into one full example. Place this into your `index.js` file and run it.

<Code lang="typescript" code={quickstartExample} title="Quickstart" />

## View your traces

The Agents SDK will automatically generate traces for you. This allows you to review how your agents
are operating, what tools they called or which agent they handed off to.

To review what happened during your agent run, navigate to the
[Trace viewer in the OpenAI Dashboard](https://platform.openai.com/traces).

## Next steps

Learn how to build more complex agentic flows:

- Learn about configuring [Agents](/openai-agents-js/guides/agents).
- Learn about [running agents](/openai-agents-js/guides/running-agents).
- Learn about [tools](/openai-agents-js/guides/tools), [guardrails](/openai-agents-js/guides/guardrails), and [models](/openai-agents-js/guides/models).
